
/*! \page secureinstallexisting Building a Secure Installation with an Existing Broker
 *
 * \htmlonly <script type="text/javascript">var randomUser1=Math.floor(Math.random()*1000000);var randomUser2=Math.floor(Math.random()*1000000);</script> \endhtmlonly
 * 
 * \section securesection Using a Secure Broker
 * 
 * In order to run outside the confines of your local machine, the
 * system must be secured with cryptographic keys against possible
 * unauthorised use of your resources.
 * 
 * To configure the user client for access to the remote Edinburgh broker,
 * use the steps outlined below, given that you have already completed the
 * steps in the \ref quickstart.
 * 
 * Depending on what you want from Acquire, you can use either 
 * the instructions on this page to build just the client parts
 * of the project for connection to the Edinburgh broker (or by
 * changing some of the connection details, to any remote broker),
 * or you can continue on to build your own broker with \ref secureinstallown.
 * This is the option that most people should choose if they
 * are not sure.
 * 
 * Please remember, if the default directory
 * <tt>/usr/local</tt> is to be used, the installation process must be
 * run as <tt>root</tt>.
 * 
 * \subsection generateclient Pairing Your Client with an Existing Broker
 * 
 * To pair a client with the broker, ensure that the broker whose keys
 * you want to download and
 * incorporate into your build is running (if the broker is local,
 * this can be achieved with a <tt>./broker</tt> in the build
 * directory in a separate terminal window). Delete any client
 * databases
 * installed that have state that could interfere with the new keys.
 * On the default install this would be: <p><tt>rm
 * ~/.AcquireLib5/client_*.db ~/.AcquireLib5/client_*.sql</tt><p>
 * Navigate
 * to the '<tt>build</tt>' directory to also ensure that the keys
 * in the build directory are removed:
 * <p><tt>rm broker.enc broker.chk</tt><p>
 * Now using: <p><tt>ccmake .</tt><p> ensure that:
 * <ul> <li>the <tt>DOWNLOAD_NEW_KEYS</tt>
 * option is set to <tt>ON</tt></li><li>the
 * <tt>INSECURE_TEST_KEYS</tt> option is set to <tt>OFF</tt></li>
 * <li>the
 * <tt>INSECURE_PASSWORDS</tt> option is set to <tt>OFF</tt> <i>(recommended, but not necessary)</i></li>
 * <li>the hostname in <tt>DEFAULT_HOST</tt> is set
 * to the host of the broker you want to pair with (e.g. for a local broker <tt>127.0.0.1</tt>,
 * or for the Edinburgh broker <tt>ssi-amrmmhd.epcc.ed.ac.uk</tt>)</li><li>the port
 * number in <tt>DEFAULT_PORT</tt> is set to the broker port (usually the default is fine)
 * that you want </li><li>the install path in
 * <tt>CMAKE_INSTALL_PREFIX</tt> is correct</li></ul>
 * Once this is complete, press 'c' and 'g' to configure,
 * generate and exit, before issuing:
 * <p><tt>cmake .; make; make install</tt><p>
 * to compile and install a new client
 * while extracting keys from the existing broker.
 * Please note that it is possible to pair with an insecure
 * broker compiled via the \ref quickstart,
 * which is not recommended.
 * 
 * If you have chosen to set <tt>INSECURE_PASSWORDS</tt> to <tt>OFF</tt>,
 * the programs will ask for passwords on their first run.
 * It should also be noted that each client generates
 * identifying keys for your user which at
 * present prevents users from switching between client programs.
 * 
 * \section testing_exist Running Tests with the Existing Broker
 * 
 * While previous tests require that you had an SSH server running on the
 * local machine, remote broker tests require that you have an account
 * on a cluster that the remote broker knows about and has access to.
 * 
 * For the purpose of these tests, we will assume that you have an
 * accessible cluster known to the broker in Edinburgh, and have
 * decided to pair with that broker.
 * 
 * \subsection tinned_cxx3 Initial Testing using the C++ Command Line Interface
 * 
 * This section tests the C++ command line client frontend for the
 * Acquire system. An example workpacket to submit is provided in the
 * '<tt>test_workpacket</tt>' subdirectory in the build directory.  It
 * is assumed that these tests are run from the build directory.
 * 
 * To run a job, first SSH-accessible machines must be added to the
 * system, either to act as gateways or machines on which cluster work
 * queues are accessible. By adding such a machine to a username
 * successfully, a user account is remotely created.
 * 
 * To add a new SSH machine via the C++ interface, use:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly
 * -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -A</tt><p>
 * 
 * When asked for a hostname, first use 'icy.cs.bris.ac.uk' and use
 * a login. Then repeat the same command again:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly
 * -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -A</tt><p>
 * This time, use 'bluecrystalp2.bris.ac.uk', as the
 * 'bluecrystalp2' cluster is associated on the broker
 * with this machine name which can be used to start work.
 * 
 * After each of these step you should see a message
 * stating that the machine has been successfully added to Acquire.
 * If you do not see this message try again and ensure that your
 * username and password are correct, the SSH server
 * is accessible and the credentials you have entered are correct.
 * 
 * A datastore can now be created around a directory that contains the
 * work that you want to run remotely. To create a remote datastore,
 * choose the directory containing the workpacket and upload a
 * description of the data so that the broker can ensure that there is
 * enough space and the data will be secure. This can be achieved
 * using: <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -d
 * ./test_workpacket/ -C</tt><p>
 * 
 * This creates a remote datastore which by default will have the
 * handle '&lt;user&gt;.workdata1', so in this case
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1\'");</script>\endhtmlonly. The view all the actors currently active, use:
 * 
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -T
 * </tt><p> This shows a tree view of the active items. To upload the
 * work data to the newly created
 * datastore, use:
 * 
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -d
 * ./test_workpacket/ -r \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1\'");</script>\endhtmlonly -U</tt><p> This both
 * uploads and marks the data as 'work', prompting the broker to then
 * choose a cluster from those you have made accessible to the system,
 * to which the work is then submitted. As this may now be a real cluster,
 * the job may have to wait in the queue to be run. Once the work is complete, to
 * get results, one must navigate the job hierarchy again. Use again:
 * <p><tt>./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -T</tt><p>This command
 * gives the status of the work. This should be complete when the
 * 'instance1' child of your workdata has reached the 'finished' state. See
 * that the first workdata has created a child instance, and that that
 * child instance, once complete, has gone on to create another
 * workdata. To download this data, use:<p><tt>mkdir -p
 * \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly; ./acquire -u \htmlonly<script type="text/javascript">document.write("test" + randomUser1);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p
 * 10000 -d \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly/ -r
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser1 + ".workdata1.instance1.workdata1\'");</script>\endhtmlonly -D</tt><p> Any data store
 * which you own and have keys for should be downloadable in this way.
 * After successfully downloading the workpacket, in the
 * <tt>\htmlonly<script type="text/javascript">document.write("\'/tmp/test" + randomUser1 + "_workpacket_output");</script>\endhtmlonly</tt>' directory you should have a
 * file '<tt>work_completed.txt</tt>' which contains a message stating
 * that the test workpacket has been completed.
 * 
 * \subsection tinned_python3 Initial Testing using the Python Command Line Interface
 * 
 * Similarly to the C++ user-facing client, SSH-accessible machines
 * must be added to the system for work to be done. This can instead
 * be achieved by using: <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n
 * ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -t hello -m &lt;<i>SSH username</i>&gt;\@icy.cs.bris.ac.uk
 * -A</tt><p> (substituting your username into this command). This adds
 * the SSH login '&lt;SSH username&gt;\@icy.cs.bris.ac.uk' to the user account
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser2 + "\'");</script>\endhtmlonly on the broker.
 * If the user does not exist, it will be
 * created. The password for the remote account is 'hello' here to
 * expedite batch processing. Also  <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n
 * ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -t hello -m &lt;<i>SSH username</i>&gt;\@bluecrystalp2.bris.ac.uk
 * -A</tt><p> (substituting your username into this command), should also be added to allow your
 * work to run remotely.
 * 
 * Once logins to clusters have been added,
 * the upload and submission can be done in a single command:
 * <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -t
 * hello -d ./test_workpacket/ -S</tt><p> Then, as before, the
 * structure can be probed by showing the nodes in the tree
 * structure. <p><tt>python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk
 * -p 10000 -t hello -T</tt><p>
 * As this may now be a real cluster,
 * the job may have to wait in the queue to be run, but
 * the running progress can be tracked.
 * Finally, once the job is complete, downloading the contents of
 * the ultimate child node (the datastore containing results) can be
 * achieved with: <p><tt>mkdir -p \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser2 + "_workpacket_output/");</script>\endhtmlonly;
 * python ./acquire.py -b broker -u \htmlonly<script type="text/javascript">document.write("test" + randomUser2);</script>\endhtmlonly -n ssi-amrmmhd.epcc.ed.ac.uk -p 10000 -t hello
 * -d \htmlonly<script type="text/javascript">document.write("/tmp/test" + randomUser2 + "_workpacket_output");</script>\endhtmlonly -r
 * \htmlonly<script type="text/javascript">document.write("\'test" + randomUser2 + ".workdata1.instance1.workdata1\'");</script>\endhtmlonly -D</tt><p> This download step
 * should be possible with any datastore created.
 * 
 * \subsection automated_python2 Using nosetests
 * 
 * The <i>nosetests</i> program can be instead used to run
 * tests on the system. Find the '<tt>tests</tt>'
 * directory inside the build directory. Edit the file
 * '<tt>test_credentials.py</tt>' to enter your
 * credentials for the machines required. If you are
 * using Bluecrystal Phase 2 to test the Edinburgh
 * broker, then '<tt>machine1</tt>'
 * is one of:<ul>
 * <li><tt>snowy.cs.bris.ac.uk</tt></li>
 * <li><tt>icy.cs.bris.ac.uk</tt></li>
 * <li><tt>grendel.chm.bris.ac.uk</tt></li>
 * <li><tt>curie.chm.bris.ac.uk</tt></li>
 * </ul>
 * and '<tt>machine2</tt>' is
 * '<tt>bluecrystalp2.bris.ac.uk</tt>'.
 * Ensure that the broker
 * is running in Edinburgh, if this is to be tested.
 * Then, in the
 * 'tests' directory, issue the command:
 * <p><tt>PYTHONPATH=.. nosetests</tt><p>
 * The automated tests should then thoroughly test the
 * remote broker system.
 * 
 * \subsection continuing2 Continuing with the Build
 * 
 * To build your own broker, continue to \ref secureinstallown. */
